using System;
using System.Runtime.InteropServices;

namespace Pegasus.Windows.API.Interfaces
{
	/// <summary>
	/// Exposed by all Shell namespace to enumerate child object of folders.
	/// </summary>
	[ComImport]
	[InterfaceType( ComInterfaceType.InterfaceIsIUnknown )]
	[Guid( "000214F2-0000-0000-C000-000000000046" )]
	public interface IEnumIDList
	{
		/// <summary>
		/// Retrieves the specified number of item identifiers in the enumeration sequence and 
		/// advances the current position by the number of items retrieved.
		/// </summary>
		/// <param name="getNum">The number of elements in the array referenced by the idList parameter.</param>
		/// <param name="idList">The address of a pointer to an array of ITEMIDLIST pointers that receive 
		/// the item identifiers. The implementation must allocate these item identifiers using CoTaskMemAlloc. 
		/// The calling application is responsible for freeing the item identifiers using CoTaskMemFree.
		/// The ITEMIDLIST structures returned in the array are relative to the IShellFolder being enumerated.</param>
		/// <returns>The count of the item identifiers actually returned in idList. The count can be smaller than the 
		/// value specified in the getNum parameter.</returns>
		int Next( int getNum, out IntPtr idList );

		/// <summary>
		/// Skips the specified number of elements in the enumeration sequence.
		/// </summary>
		/// <param name="skipNum">The number of item identifiers to skip.</param>
		void Skip( uint skipNum );

		/// <summary>
		/// Returns to the beginning of the enumeration sequence.
		/// </summary>
		void Reset();

		/// <summary>
		/// Creates a new item enumeration object with the same contents and state as the current one. 
		/// </summary>
		/// <returns>the new enumeration object. The calling application must eventually free the new object by 
		/// calling the Release function.</returns>
		IEnumIDList Clone();
	}
}
